Connectivity Software User's Guide and Reference
Sparkplug Metric Data Type Considerations
Rapid Toolkit for Sparkplug > Concepts > Developing Sparkplug Edge Nodes > Sparkplug Metric Configuration > Sparkplug Metric Data Type Considerations
In This Topic

Introduction

Because the data type model in Sparkplug is not identical with the .NET type model, you need to understand what the type correspondences are, and in some cases the Sparkplug data types are represented by .NET types that differ from intuitive expectations. To learn about the representation of Sparkplug data types in Connectivity Software, see DataTypes in Rapid Toolkit for Sparkplug.

The Unknown Sparkplug Data Type

By default, the DataType Property of a SparkplugMetric (e.g. created with a default constructor) is set to Unknown. In Sparkplug, Unknown is a data type placeholder for future expansion. Rapid Toolkit for Sparkplug uses Unknown in the DataType Property as an indication that the data type of the metric is not known upfront, and should be determined based on the actual metric data being passed to or from the metric. This is a special behavior reserved for specific use cases. For Sparkplug compliance and interoperability, it is strongly recommended that you always set the DataType Property to a specific data type other than Unknown.

You can set the DataType Property explicitly from your code, However, when you use the extension methods for Sparkplug Metric Configuration, many of them either allow you to pass in the data type as a parameter, or they actually infer the data type automatically (in compile-time).

Data Types in Data Provision

Refresher: In the context of Sparkplug edge node/device development, by "data provision", we understand the process through which your code provides data that is published by the Spakrplug edge node or device, ans subsequently subscribed to by Sparkplug host applications.

Pull Data Provision Model

When you use the extension method for Sparkplug Metric Configuration, and provide a function that handles the Read request, Rapid Toolkit for Sparkplug determines the Sparkplug data type of the metric from the .NET type of the function argument. For example, if you use the simplest ReadValueFunction method overload and simply pass it a function that returns System.Int32 type, the Sparkplug data type (the DataType Property of the metric) will be automatically determined to be SparkplugDataType.Int32.

There are cases, however, when this automatic mechanism is not suitable; if so, you can still use the extension methods for metric configuration, but you have to specify the desired data type in some additional ways. This happens e.g. when multiple Sparkplug data types are mapped to a single .NET type (as per Data Types in Rapid Toolkit for Sparkplug article). In the example given above, Rapid Toolkit for Sparkplug uses System.Int32 not only for Sparkplug's Int32 data type, but also for UInt16 (this is for it to be CLS-compliant and usable from languages like VB.NET; similarly with some other integer types). If you want your metric be of Sparkplug Int8, UInt16, UInt32 or UInt64 data type, you can do it similarly to the following example.

Example

.NET

// This example shows how to create a metric of type UInt16 and implement reading its value using a function.
//
// You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
// program, to subscribe to the edge node data. 
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
// Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using OpcLabs.EasySparkplug;
using System;

namespace SparkplugDocExamples.EdgeNode._SparkplugMetric
{
    partial class ReadValueFunction
    {
        static public void UInt16()
        {
            // Note that the default port for the "mqtt" scheme is 1883.
            var hostDescriptor = new SparkplugHostDescriptor("mqtt://localhost");

            // Instantiate the edge node object and hook events.
            var edgeNode = new EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo");
            edgeNode.SystemConnectionStateChanged += (sender, eventArgs) =>
            {
                // Display the new connection state (such as when the connection to the broker succeeds or fails).
                Console.WriteLine($"{nameof(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}");
            };

            // Create a metric, defining its read values by a function.
            // We explicitly specify the Sparkplug data type of the metric to be UInt16. The read value function can then
            // return any type of object, and EasySparkplug will attempt to convert it to the specified Sparkplug data type.
            // This is helpful in languages like VB.NET that do not have full support for some types (such as unsigned
            // integers).
            var random = new Random();
            edgeNode.Add(new SparkplugMetric("ReadThisMetric").ReadValueFunction(
                typeof(UInt16), () => random.Next(65536)));

            // Start the edge node.
            Console.WriteLine("The edge node is starting...");
            edgeNode.Start();

            Console.WriteLine("The edge node is started.");
            Console.WriteLine();

            // Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...");
            Console.ReadLine();

            // Stop the edge node.
            Console.WriteLine("The edge node is stopping...");
            edgeNode.Stop();

            Console.WriteLine("The edge node is stopped.");
        }
    }
}

' This example shows how to create a metric of type UInt16 and implement reading its value using a function.
'
' You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
' program, to subscribe to the edge node data.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
' Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasySparkplug

Namespace Global.SparkplugDocExamples.EdgeNode._SparkplugMetric
    Partial Class ReadValueFunction
        Public Shared Sub UInt16()
            ' Note that the default port for the "mqtt" scheme is 1883.
            Dim hostDescriptor = New SparkplugHostDescriptor("mqtt://localhost")

            ' Instantiate the edge node object and hook events.
            Dim edgeNode = New EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo")
            AddHandler edgeNode.SystemConnectionStateChanged,
                Sub(sender, eventArgs)
                    ' Display the new connection state (such as when the connection to the broker succeeds or fails).
                    Console.WriteLine($"{NameOf(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}")
                End Sub

            ' Create a metric, defining its read values by a function.
            ' We explicitly specify the Sparkplug data type of the metric to be UInt16. The read value function can then
            ' return any type of object, and EasySparkplug will attempt to convert it to the specified Sparkplug data type.
            ' This is helpful in languages like VB.NET that do not have full support for some types (such as unsigned
            ' integers).
            Dim random = New Random()
            edgeNode.Add(New SparkplugMetric("ReadThisMetric").ReadValueFunction(
                GetType(UInt16), Function() random.Next(65536)))

            ' Start the edge node.
            Console.WriteLine("The edge node is starting...")
            edgeNode.Start()

            Console.WriteLine("The edge node is started.")
            Console.WriteLine()

            ' Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...")
            Console.ReadLine()

            ' Stop the edge node.
            Console.WriteLine("The edge node is stopping...")
            edgeNode.Stop()

            Console.WriteLine("The edge node is stopped.")
        End Sub
    End Class
End Namespace

 

Also, in Sparkplug, there is a Bytes type, which physically is the same as UInt8Array. When Rapid Toolkit for Sparkplug methods encounter a .NET array of bytes, they prefer to choose the Sparkplug Bytes data type for it, unless specified otherwise. The following example illustrates an implementation of a readable metric with Sparkplug data type Bytes.

Example

.NET

// This example shows how to create a metric of Sparkplug data type Bytes and implement its reading using a function.
//
// You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
// program, to subscribe to the edge node data. 
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
// Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using OpcLabs.EasySparkplug;
using System;

namespace SparkplugDocExamples.EdgeNode._SparkplugMetric
{
    partial class ReadValueFunction
    {
        static public void Bytes()
        {
            // Note that the default port for the "mqtt" scheme is 1883.
            var hostDescriptor = new SparkplugHostDescriptor("mqtt://localhost");

            // Instantiate the edge node object and hook events.
            var edgeNode = new EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo");
            edgeNode.SystemConnectionStateChanged += (sender, eventArgs) =>
            {
                // Display the new connection state (such as when the connection to the broker succeeds or fails).
                Console.WriteLine($"{nameof(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}");
            };

            // Create a metric, defining its read values by a function.
            // The type of the metric (Bytes, in this case) is inferred from the type returned by the function.
            // An array of .NET Byte is used to represent the Bytes.
            var random = new Random();
            edgeNode.Add(new SparkplugMetric("ReadThisMetric").ReadValueFunction(() =>
            {
                var buffer = new byte[20];
                random.NextBytes(buffer);
                return buffer;
            }));

            // Start the edge node.
            Console.WriteLine("The edge node is starting...");
            edgeNode.Start();

            Console.WriteLine("The edge node is started.");
            Console.WriteLine();

            // Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...");
            Console.ReadLine();

            // Stop the edge node.
            Console.WriteLine("The edge node is stopping...");
            edgeNode.Stop();

            Console.WriteLine("The edge node is stopped.");
        }
    }
}

' This example shows how to create a metric of Sparkplug data type Bytes and implement its reading using a function.
'
' You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
' program, to subscribe to the edge node data.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
' Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasySparkplug

Namespace Global.SparkplugDocExamples.EdgeNode._SparkplugMetric
    Partial Class ReadValueFunction
        Public Shared Sub Bytes()
            ' Note that the default port for the "mqtt" scheme is 1883.
            Dim hostDescriptor = New SparkplugHostDescriptor("mqtt://localhost")

            ' Instantiate the edge node object and hook events.
            Dim edgeNode = New EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo")
            AddHandler edgeNode.SystemConnectionStateChanged,
                Sub(sender, eventArgs)
                    ' Display the new connection state (such as when the connection to the broker succeeds or fails).
                    Console.WriteLine($"{NameOf(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}")
                End Sub

            ' Create a metric, defining its read values by a function.
            ' The type of the metric (Bytes, in this case) is inferred from the type returned by the function.
            ' An array of .NET Byte is used to represent the Bytes.
            Dim random = New Random()
            edgeNode.Add(New SparkplugMetric("ReadThisMetric").ReadValueFunction(
                         Function()
                             Dim buffer = New Byte(19) {}
                             random.NextBytes(buffer)
                             Return buffer
                         End Function
                ))

            ' Start the edge node.
            Console.WriteLine("The edge node is starting...")
            edgeNode.Start()

            Console.WriteLine("The edge node is started.")
            Console.WriteLine()

            ' Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...")
            Console.ReadLine()

            ' Stop the edge node.
            Console.WriteLine("The edge node is stopping...")
            edgeNode.Stop()

            Console.WriteLine("The edge node is stopped.")
        End Sub
    End Class
End Namespace

 

Push Data Provision Model

In the Push Data Provision Model, the concerns described above with the Pull Data Provision Model still apply. However, since in the configuration methods there is no function provided with an argument from which the data type can be automatically determined, you will end up specifying the data type yourself, typically by some overload of the ValueType Method.

Example

.NET

// This example shows how to update the read value in the push data provision model. In this model, your code pushes the
// data into the edge node or device, and the edge node or device then makes the data available over Sparkplug.
//
// You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
// program, to subscribe to the edge node data. 
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
// Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using OpcLabs.EasySparkplug;
using System;
using Timer = System.Timers.Timer;

namespace SparkplugDocExamples.EdgeNode._SparkplugMetric
{
    class UpdateReadData
    {
        static public void Main1()
        {
            // Note that the default port for the "mqtt" scheme is 1883.
            var hostDescriptor = new SparkplugHostDescriptor("mqtt://localhost");

            // Instantiate the edge node object and hook events.
            var edgeNode = new EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo");
            edgeNode.SystemConnectionStateChanged += (sender, eventArgs) =>
            {
                // Display the new connection state (such as when the connection to the broker succeeds or fails).
                Console.WriteLine($"{nameof(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}");
            };

            // Create a read-only data metric.
            var metric = SparkplugMetric.CreateIn(edgeNode, "ReadThisMetric")
                .ValueType<int>()
                .Writable(false);

            // Create a timer for pushing the data to the metric. In a real edge node or device, the activity may also come
            // from other sources.
            var timer = new Timer
            {
                Interval = 1000,    // 1 second
                AutoReset = true,
            };

            // Set the read data of the metric to a random value whenever the timer interval elapses.
            var random = new Random();
            timer.Elapsed += (sender, args) => metric.UpdateReadData(random.Next());
            timer.Start();

            // Start the edge node.
            Console.WriteLine("The edge node is starting...");
            edgeNode.Start();

            Console.WriteLine("The edge node is started.");
            Console.WriteLine();

            // Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...");
            Console.ReadLine();

            // Stop the edge node.
            Console.WriteLine("The edge node is stopping...");
            edgeNode.Stop();

            Console.WriteLine("The edge node is stopped.");

            // Stop the timer.
            timer.Stop();
        }
    }
}

' This example shows how to update the read value in the push data provision model. In this model, your code pushes the
' data into the edge node or device, and the edge node or device then makes the data available over Sparkplug.
'
' You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
' program, to subscribe to the edge node data.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
' Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasySparkplug
Imports Timer = System.Timers.Timer

Namespace Global.SparkplugDocExamples.EdgeNode._SparkplugMetric
    Class UpdateReadData
        Public Shared Sub Main1()
            ' Note that the default port for the "mqtt" scheme is 1883.
            Dim hostDescriptor = New SparkplugHostDescriptor("mqtt://localhost")

            ' Instantiate the edge node object and hook events.
            Dim edgeNode = New EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo")
            AddHandler edgeNode.SystemConnectionStateChanged,
                Sub(sender, eventArgs)
                    ' Display the new connection state (such as when the connection to the broker succeeds or fails).
                    Console.WriteLine($"{NameOf(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}")
                End Sub

            ' Create a read-only data metric.
            Dim metric = SparkplugMetric.CreateIn(edgeNode, "ReadThisMetric") _
                .ValueType(Of Integer)() _
                .Writable(False)

            ' Create a timer for pushing the data to the metric. In a real edge node or device, the activity may also come
            ' from other sources.
            Dim timer = New Timer With
            {
                .Interval = 1000, ' 1 second
                .AutoReset = True
            }

            ' Set the read data of the metric to a random value whenever the timer interval elapses.
            Dim random = New Random()
            AddHandler timer.Elapsed, Sub(s, a) metric.UpdateReadData(random.Next())
            timer.Start()

            ' Start the edge node.
            Console.WriteLine("The edge node is starting...")
            edgeNode.Start()

            Console.WriteLine("The edge node is started.")
            Console.WriteLine()

            ' Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...")
            Console.ReadLine()

            ' Stop the edge node.
            Console.WriteLine("The edge node is stopping...")
            edgeNode.Stop()

            Console.WriteLine("The edge node is stopped.")

            ' Stop the timer.
            timer.Stop()
        End Sub
    End Class
End Namespace

 

Data Types in Data Consumption

Refresher: In the context of Sparkplug edge node/device development, by "data consumption", we understand the process through which your code consumes the commands that it receives from Sparkplug host applications.

Push Data Consumption Model

When you use some extension method for Sparkplug Metric Configuration, and provide a function (or action) that handles the Write request, Rapid Toolkit for Sparkplug determines the Sparkplug data type of the metric from the .NET type of the function (or action) argument. For example, if you use the simplest WriteValueAction method overload and simply pass it an action that takes System.Int32 argument, the Sparkplug data type (the DataType Property of the metric) will be automatically determined to be SparkplugDataType.Int32.

There are cases, however, when this automatic mechanism is not suitable; if so, you can still use the extension methods for metric configuration, but you have to specify the desired data type in some additional ways. This happens e.g. when multiple Sparkplug data types are mapped to a single .NET type (as per Data Types in Rapid Toolkit for Sparkplug article). In the example given above, Rapid Toolkit for Sparkplug uses System.Int32 not only for Sparkplug's Int32 data type, but also for UInt16 (this is for it to be CLS-compliant and usable from languages like VB.NET; similarly with some other integer types). If you want your metric be of Sparkplug Int8, UInt16, UInt32 or UInt64 data type, you can do it similarly to the following example.

Example

.NET

// This example shows how to define a metric of Sparkplug data type UInt16 and use an action to its write behavior.
// This is an example of the push data consumption model.
//
// You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
// program, to subscribe to the edge node data. SparkplugCmd, or other capable Sparkplug application, can be used to write
// data into the metric.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
// Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using OpcLabs.EasySparkplug;
using System;

namespace SparkplugDocExamples.EdgeNode._SparkplugMetric
{
    partial class WriteValueAction
    {
        static public void UInt16()
        {
            // Note that the default port for the "mqtt" scheme is 1883.
            var hostDescriptor = new SparkplugHostDescriptor("mqtt://localhost");

            // Instantiate the edge node object and hook events.
            var edgeNode = new EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo");
            edgeNode.SystemConnectionStateChanged += (sender, eventArgs) =>
            {
                // Display the new connection state (such as when the connection to the broker succeeds or fails).
                Console.WriteLine($"{nameof(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}");
            };

            // Create a writable metric and add an action that will be executed when the metric is written to.
            // We explicitly specify the Sparkplug data type of the variable to be UInt16, but use .NET Int32 in the write value
            // function. EasySparkplug will attempt to convert the value being written to the specified .NET type. This is
            // helpful in languages like VB.NET that do not have full support for some types (such as unsigned integers).
            edgeNode.Add(new SparkplugMetric("WriteToThisMetric").WriteValueAction<int>(
                typeof(UInt16),
                value => Console.WriteLine($"Value written: {value}")));

            // Start the edge node.
            Console.WriteLine("The edge node is starting...");
            edgeNode.Start();

            Console.WriteLine("The edge node is started.");
            Console.WriteLine();

            // Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...");
            Console.ReadLine();

            // Stop the edge node.
            Console.WriteLine("The edge node is stopping...");
            edgeNode.Stop();

            Console.WriteLine("The edge node is stopped.");
        }
    }
}

' This example shows how to define a metric of Sparkplug data type UInt16 and use an action to its write behavior.
' This is an example of the push data consumption model.
'
' You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
' program, to subscribe to the edge node data. SparkplugCmd, or other capable Sparkplug application, can be used to write
' data into the metric.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
' Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasySparkplug

Namespace Global.SparkplugDocExamples.EdgeNode._SparkplugMetric
    Partial Class WriteValueAction
        Public Shared Sub UInt16()
            ' Note that the default port for the "mqtt" scheme is 1883.
            Dim hostDescriptor = New SparkplugHostDescriptor("mqtt://localhost")

            ' Instantiate the edge node object and hook events.
            Dim edgeNode = New EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo")
            AddHandler edgeNode.SystemConnectionStateChanged,
                Sub(sender, eventArgs)
                    ' Display the new connection state (such as when the connection to the broker succeeds or fails).
                    Console.WriteLine($"{NameOf(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}")
                End Sub

            ' Create a writable metric and add an action that will be executed when the metric is written to.
            ' We explicitly specify the Sparkplug data type of the variable to be UInt16, but use .NET Int32 in the write value
            ' function. EasySparkplug will attempt to convert the value being written to the specified .NET type. This is
            ' helpful in languages like VB.NET that do not have full support for some types (such as unsigned integers).
            edgeNode.Add(New SparkplugMetric("WriteToThisMetric").WriteValueAction(Of Integer)(
                GetType(UInt16),
                Sub(value) Console.WriteLine($"Value written: {value}")))

            ' Start the edge node.
            Console.WriteLine("The edge node is starting...")
            edgeNode.Start()

            Console.WriteLine("The edge node is started.")
            Console.WriteLine()

            ' Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...")
            Console.ReadLine()

            ' Stop the edge node.
            Console.WriteLine("The edge node is stopping...")
            edgeNode.Stop()

            Console.WriteLine("The edge node is stopped.")
        End Sub
    End Class
End Namespace

 

Also, in Sparkplug, there is a Bytes type, which physically is the same as UInt8Array. When Rapid Toolkit for Sparkplug methods encounter a .NET array of bytes, they prefer to choose the Sparkplug Bytes data type for it, unless specified otherwise. The following example illustrates an implementation of a  writable metric with Sparkplug data type Bytes.

Example

.NET

// This example shows how to define a metric of Sparkplug data type Bytes and use an action to its write behavior.
// This is an example of the push data consumption model.
//
// You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
// program, to subscribe to the edge node data. SparkplugCmd, or other capable Sparkplug application, can be used to write
// data into the metric.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
// Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using OpcLabs.EasySparkplug;
using System;

namespace SparkplugDocExamples.EdgeNode._SparkplugMetric
{
    partial class WriteValueAction
    {
        static public void Bytes()
        {
            // Note that the default port for the "mqtt" scheme is 1883.
            var hostDescriptor = new SparkplugHostDescriptor("mqtt://localhost");

            // Instantiate the edge node object and hook events.
            var edgeNode = new EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo");
            edgeNode.SystemConnectionStateChanged += (sender, eventArgs) =>
            {
                // Display the new connection state (such as when the connection to the broker succeeds or fails).
                Console.WriteLine($"{nameof(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}");
            };

            // Create a writable metric and add an action that will be executed when the metric is written to.
            edgeNode.Add(new SparkplugMetric("WriteToThisMetric").WriteValueAction<byte[]>(value =>
                Console.WriteLine($"Value written: {((value is null) ? String.Empty : BitConverter.ToString(value))}")));

            // Start the edge node.
            Console.WriteLine("The edge node is starting...");
            edgeNode.Start();

            Console.WriteLine("The edge node is started.");
            Console.WriteLine();

            // Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...");
            Console.ReadLine();

            // Stop the edge node.
            Console.WriteLine("The edge node is stopping...");
            edgeNode.Stop();

            Console.WriteLine("The edge node is stopped.");
        }
    }
}

' This example shows how to define a metric of Sparkplug data type Bytes and use an action to its write behavior.
' This is an example of the push data consumption model.
'
' You can use any Sparkplug application, including our SparkplugCmd utility and the SparkplugApplicationConsoleDemo
' program, to subscribe to the edge node data. SparkplugCmd, or other capable Sparkplug application, can be used to write
' data into the metric.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-ConnectivityStudio/Latest/examples.html .
' Sparkplug examples in C# on GitHub: https://github.com/OPCLabs/Examples-ConnectivityStudio-CSharp .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.EasySparkplug

Namespace Global.SparkplugDocExamples.EdgeNode._SparkplugMetric
    Partial Class WriteValueAction
        Public Shared Sub Bytes()
            ' Note that the default port for the "mqtt" scheme is 1883.
            Dim hostDescriptor = New SparkplugHostDescriptor("mqtt://localhost")

            ' Instantiate the edge node object and hook events.
            Dim edgeNode = New EasySparkplugEdgeNode(hostDescriptor, "easyGroup", "easySparkplugDemo")
            AddHandler edgeNode.SystemConnectionStateChanged,
                Sub(sender, eventArgs)
                    ' Display the new connection state (such as when the connection to the broker succeeds or fails).
                    Console.WriteLine($"{NameOf(EasySparkplugEdgeNode.SystemConnectionStateChanged)}: {eventArgs}")
                End Sub

            ' Create a writable metric and add an action that will be executed when the metric is written to.
            edgeNode.Add(New SparkplugMetric("WriteToThisMetric").WriteValueAction(Of Byte())(
                Sub(value)
                    Console.WriteLine($"Value written: {(If(value Is Nothing, String.Empty, BitConverter.ToString(value)))}")
                End Sub))

            ' Start the edge node.
            Console.WriteLine("The edge node is starting...")
            edgeNode.Start()

            Console.WriteLine("The edge node is started.")
            Console.WriteLine()

            ' Let the user decide when to stop.
            Console.WriteLine("Press Enter to stop the edge node...")
            Console.ReadLine()

            ' Stop the edge node.
            Console.WriteLine("The edge node is stopping...")
            edgeNode.Stop()

            Console.WriteLine("The edge node is stopped.")
        End Sub
    End Class
End Namespace

 

Pull Data Consumption Model

In the Pull Data Consumption Model, the concerns described above with the Push Data Consumption Model still apply. However, since in the configuration methods there is no function or action provided with an argument from which the data type can be automatically determines, you will end up specifying the data type yourself, typically by some overload of the ValueType Method.

 

Sparkplug is a trademark of Eclipse Foundation, Inc. "MQTT" is a trademark of the OASIS Open standards consortium. Other related terms are trademarks of their respective owners. Any use of these terms on this site is for descriptive purposes only and does not imply any sponsorship, endorsement or affiliation.

 

 

Copyright © 2004-2025 CODE Consulting and Development, s.r.o., Plzen. All rights reserved. Web page: www.opclabs.com

Documentation Home, Send Feedback. Resources: Knowledge Base, Product Downloads. Technical support: Online Forums, FAQ.

Missing some example? Ask us for it on our Online Forums! You do not have to own a commercial license in order to use Online Forums, and we reply to every post.